
<!DOCTYPE html
  PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
   <head>
      <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
   
      <title>2.3.&nbsp;文档化函数</title>
      <link rel="stylesheet" href="../diveintopython.css" type="text/css">
      <link rev="made" href="mailto:f8dy@diveintopython.org">
      <meta name="generator" content="DocBook XSL Stylesheets V1.52.2">
      <meta name="keywords" content="Python, Dive Into Python, tutorial, object-oriented, programming, documentation, book, free">
      <meta name="description" content="Python from novice to pro">
      <link rel="home" href="../toc/index.html" title="Dive Into Python">
      <link rel="up" href="index.html" title="第&nbsp;2&nbsp;章&nbsp;第一个 Python 程序">
      <link rel="previous" href="declaring_functions.html" title="2.2.&nbsp;函数声明">
      <link rel="next" href="everything_is_an_object.html" title="2.4.&nbsp;万物皆对象">
   </head>
   <body>
      <table id="Header" width="100%" border="0" cellpadding="0" cellspacing="0" summary="">
         <tr>
            <td id="breadcrumb" colspan="5" align="left" valign="top">导航：<a href="../index.html">起始页</a>&nbsp;&gt;&nbsp;<a href="../toc/index.html">Dive Into Python</a>&nbsp;&gt;&nbsp;<a href="index.html">第一个 Python 程序</a>&nbsp;&gt;&nbsp;<span class="thispage">文档化函数</span></td>
            <td id="navigation" align="right" valign="top">&nbsp;&nbsp;&nbsp;<a href="declaring_functions.html" title="上一页: “函数声明”">&lt;&lt;</a>&nbsp;&nbsp;&nbsp;<a href="everything_is_an_object.html" title="下一页: “万物皆对象”">&gt;&gt;</a></td>
         </tr>
         <tr>
            <td colspan="3" id="logocontainer">
               <h1 id="logo"><a href="../index.html" accesskey="1">深入 Python :Dive Into Python 中文版</a></h1>
               <p id="tagline">Python 从新手到专家 [Dip_5.4b_CPyUG_Release]</p>
            </td>
            <td colspan="3" align="right">
               <form id="search" method="GET" action="http://www.google.com/custom">
                  <p><label for="q" accesskey="4">Find:&nbsp;</label><input type="text" id="q" name="q" size="20" maxlength="255" value=""> <input type="submit" value="搜索"><input type="hidden" name="domains" value="woodpecker.org.cn/diveintopython"><input type="hidden" name="sitesearch" value="www.woodpecker.org.cn/diveintopython"></p>
               </form>
            </td>
         </tr>
      </table>
      <!--#include virtual="/inc/ads" -->
      <div class="section" lang="zh_cn">
         <div class="titlepage">
            <div>
               <div>
                  <h2 class="title"><a name="odbchelper.docstring"></a>2.3.&nbsp;文档化函数
                  </h2>
               </div>
            </div>
            <div></div>
         </div>
         <div class="abstract">
            <p>可以通过给出一个 <tt class="literal">doc string</tt> (文档字符串) 来文档化一个 <span class="application">Python</span> 函数。
            </p>
         </div>
         <div class="example"><a name="odbchelper.triplequotes"></a><h3 class="title">例&nbsp;2.2.&nbsp;定义 <tt class="function">buildConnectionString</tt> 函数的 <tt class="literal">doc string</tt></h3><pre class="programlisting"><span class='pykeyword'>
def</span> buildConnectionString(params):
    <span class='pystring'>"""Build a connection string from a dictionary of parameters.

    Returns string."""</span></pre><p>三重引号表示一个多行字符串。在开始与结束引号间的所有东西都被视为单个字符串的一部分，包括硬回车和其它的引号字符。您可以在任何地方使用它们，但是您可能会发现，它们经常被用于定义 <tt class="literal">doc string</tt>。
            </p>
         </div><a name="compare.quoting.perl"></a><table class="note" border="0" summary="">
            <tr>
               <td rowspan="2" align="center" valign="top" width="1%"><img src="../images/note.png" alt="注意" title="" width="24" height="24"></td>
            </tr>
            <tr>
               <td colspan="2" align="left" valign="top" width="99%">三重引号也是一种定义既包含单引号又包含双引号的字符串的简单方法，就像 <span class="application">Perl</span> 中的 <tt class="literal">qq/.../</tt> 。
               </td>
            </tr>
         </table>
         <p>在三重引号中的任何东西都是这个函数的 <tt class="literal">doc string</tt>，它们用来说明函数可以做什么。如果存在 <tt class="literal">doc string</tt>，它必须是一个函数要定义的第一个内容 (也就是说，在冒号后面的第一个内容)。在技术上不要求给出函数的 <tt class="literal">doc string</tt>，但是您应该这样做。我相信在您上过的每一种编程课上都听到过这一点，但是 <span class="application">Python</span> 带给您一些额外的动机：<tt class="literal">doc string</tt> 在运行时可作为函数的属性。
         </p><a name="tip.docstring"></a><table class="note" border="0" summary="">
            <tr>
               <td rowspan="2" align="center" valign="top" width="1%"><img src="../images/note.png" alt="注意" title="" width="24" height="24"></td>
            </tr>
            <tr>
               <td colspan="2" align="left" valign="top" width="99%">许多 <span class="application">Python</span> <span class="acronym">IDE</span> 使用 <tt class="literal">doc string</tt> 来提供上下文敏感的文档信息，所以当键入一个函数名时，它的 <tt class="literal">doc string</tt> 显示为一个工具提示。这一点可以说非常有用，但是它的好坏取决于您书写的 <tt class="literal">doc string</tt> 的好坏。
               </td>
            </tr>
         </table>
         <div class="furtherreading">
            <h3>进一步阅读</h3>
            <ul>
               <li><a href="http://www.python.org/peps/pep-0257.html">PEP 257</a> 定义了 <tt class="literal">doc string</tt> 规范。
               </li>
               <li><a href="http://www.python.org/doc/essays/styleguide.html"><i class="citetitle"><span class="application">Python</span> Style Guide</i></a> 讨论了如何编写一个好的 <tt class="literal">doc string</tt>。
               </li>
               <li><a href="http://www.python.org/doc/current/tut/tut.html"><i class="citetitle"><span class="application">Python</span> Tutorial</i></a> 讨论了<a href="http://www.python.org/doc/current/tut/node6.html#SECTION006750000000000000000">在 <tt class="literal">doc string</tt> 中如何使用空白</a>。
               </li>
            </ul>
         </div>
      </div>
      <table class="Footer" width="100%" border="0" cellpadding="0" cellspacing="0" summary="">
         <tr>
            <td width="35%" align="left"><br><a class="NavigationArrow" href="declaring_functions.html">&lt;&lt;&nbsp;函数声明</a></td>
            <td width="30%" align="center"><br>&nbsp;<span class="divider">|</span>&nbsp;<a href="index.html#odbchelper.divein" title="2.1.&nbsp;概览">1</a> <span class="divider">|</span> <a href="declaring_functions.html" title="2.2.&nbsp;函数声明">2</a> <span class="divider">|</span> <span class="thispage">3</span> <span class="divider">|</span> <a href="everything_is_an_object.html" title="2.4.&nbsp;万物皆对象">4</a> <span class="divider">|</span> <a href="indenting_code.html" title="2.5.&nbsp;代码缩进">5</a> <span class="divider">|</span> <a href="testing_modules.html" title="2.6.&nbsp;测试模块">6</a>&nbsp;<span class="divider">|</span>&nbsp;
            </td>
            <td width="35%" align="right"><br><a class="NavigationArrow" href="everything_is_an_object.html">万物皆对象&nbsp;&gt;&gt;</a></td>
         </tr>
         <tr>
            <td colspan="3"><br></td>
         </tr>
      </table>
      <div class="Footer">
         <p class="copyright">Copyright © 2000, 2001, 2002, 2003, 2004 <a href="mailto:mark@diveintopython.org">Mark Pilgrim</a></p>
         <p class="copyright">Copyright © 2001, 2002, 2003, 2004, 2005, 2006, 2007 <a href="mailto:python-cn@googlegroups.com">CPyUG (邮件列表)</a></p>
      </div>
   </body>
</html>